home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 10 / AACD 10.iso / AACD / Resources / Online / Term / Extras / HydraCom / hydracom-source.lha / Rendezvous.h < prev    next >
C/C++ Source or Header  |  1996-10-11  |  7KB  |  209 lines
  1. /*
  2. **    Rendezvous.h - External program interface for Amiga
  3. **                   telecommunications software
  4. **
  5. **    Written by Olaf Barthel, freely distributable.
  6. **
  7. **    :ts=8
  8. */
  9.  
  10.     /* Minimum rendezvous data structure revision. */
  11.  
  12. #define RENDEZVOUS_VERSION    0
  13.  
  14.     /* Returned by rs_Login(). */
  15.  
  16. struct RendezvousData
  17. {
  18.     LONG             rd_Version;        /* Version of this data structure. */
  19.     struct Screen        *rd_Screen;        /* Pointer to terminal screen. */
  20.     struct IOExtSer         rd_ReadRequest,    /* Serial read request. */
  21.                  rd_WriteRequest;    /* Serial write request. */
  22.  
  23.     struct List         rd_UploadList,        /* List of files to upload. */
  24.                  rd_DownloadList,    /* List of files to receive. */
  25.  
  26.                  rd_SentList,        /* List of files sent (uploaded). */
  27.                  rd_ReceivedList;    /* List of files received (downloaded). */
  28.  
  29.     STRPTR             rd_SendPath,        /* Path to look into for files to send. */
  30.                  rd_ReceivePath,    /* Path to place files into when receiving. */
  31.  
  32.                  rd_Options;        /* Protocol options, command line parameters, etc. */
  33. };
  34.  
  35.     /* Rendezvous interface data, this is what FindSemaphore()
  36.      * returns.
  37.      */
  38.  
  39. struct RendezvousSemaphore
  40. {
  41.     struct SignalSemaphore    rs_Semaphore;        /* Link access. */
  42.  
  43.     LONG            rs_Version;        /* Data structure version. */
  44.  
  45.         /* Callback routines follow below. */
  46.  
  47.     struct RendezvousData *    (* __asm rs_Login)(register __a0 struct MsgPort *ReadPort,register __a1 struct MsgPort *WritePort,register __a2 struct TagItem *TagList);
  48.     VOID            (* __asm rs_Logoff)(register __a0 struct RendezvousData *Data);
  49.     struct Node *        (* __asm rs_NewNode)(register __a0 STRPTR Name);
  50. };
  51.  
  52. /***********************************************************************
  53.  
  54. About the rendezvous interface
  55. ==============================
  56. `term' 4.0 provides an interface for other client program to gain control
  57. over the serial driver. In order to do so, the following needs to be done
  58. (code fragment follows):
  59.  
  60.    struct RendezvousSemaphore *Semaphore;
  61.  
  62.    Forbid();
  63.  
  64.       // Find the access semaphore, note that "TERM" can be any
  65.       // other interface name, provided it is unique.
  66.  
  67.    if(Semaphore = (struct RendezvousSemaphore *)FindSemaphore("TERM"))
  68.    {
  69.       ObtainSemaphore(Semaphore);
  70.  
  71.       Permit();
  72.    }
  73.    else
  74.       Permit();
  75.  
  76. Once the client has acquired the RendezvousSemaphore it can access the
  77. data attached to it. Please note that the contents of the
  78. RendezvousSemaphore are read-only. The rs_Version entry indicates which
  79. entries and routines are available in this data structure. Please note
  80. that the data structure may grow in the future.
  81.  
  82. To link to to `term', call the rs_Login() routine, such as shown
  83. below:
  84.  
  85.    struct MsgPort        *ReadPort,
  86.                          *WritePort;
  87.    struct RendezvousData *Data;
  88.  
  89.    if(ReadPort = CreateMsgPort())
  90.    {
  91.       if(WritePort = CreateMsgPort())
  92.       {
  93.           if(Data = (*Semaphore -> rs_Login)(ReadPort,WritePort,NULL))
  94.           {
  95.              // Work with it.
  96.  
  97.              :
  98.              :
  99.              :
  100.  
  101. Make sure that you get what you want, rs_Login() may return NULL in case
  102. of failure.
  103.  
  104.  
  105. The RendezvousData structure
  106. ============================
  107. Let's have a look at the contents of the RendezvousData structure:
  108.  
  109. 1. rd_Version [read-only]
  110.  
  111. Just like the RendezvousSemaphore it includes a version entry (rd_Version)
  112. to help you to find out which entries are present and which are not
  113. (remember that this data structure may grow in the future).
  114.  
  115. 2. rd_Screen [read-only]
  116.  
  117. Here you can find a pointer to the screen `term' uses or a NULL in case
  118. `term' could not return a proper address. You can use this screen to
  119. open your windows on it.
  120.  
  121. 3. rd_ReadRequest, rd_WriteRequest
  122.  
  123. These are ready-to-use serial I/O requests for your program. The
  124. rs_Login() call will have placed your ReadPort and WritePort pointers
  125. in these requests for you to use.
  126.  
  127. 4. rd_UploadList
  128.  
  129. This is a standard List with plain Nodes in it. Each node contains the
  130. name of a file to upload. You are requested to process this list if
  131. possible. When you are finished uploading a file, Remove() the
  132. corresponding Node from this list and AddTail() it to the rd_SentList.
  133.  
  134. 5. rd_DownloadList
  135.  
  136. This is another standard Listh with plain Nodes in it. Each of these
  137. nodes contains the name of a file to receive, or to request from the
  138. remote. You are requested to process this list if possible. When you
  139. are finished receiving a file whose name could be found in the list,
  140. Remove() the corresponding Node from this list and AddTail() it to
  141. the rd_ReceivedList.
  142.  
  143. 6. rd_SentList
  144.  
  145. After having sent a file whose name could not be found on the
  146. rd_UploadList, allocate a Node using the rs_NewNode() call with
  147. the name of the file as the parameter and AddTail() it to this list.
  148.  
  149. 7. rd_ReceivedList
  150.  
  151. After having received a file whose name could not be found on the
  152. rd_DownloadList, allocate a Node using the rs_NewNode() call with
  153. the name of the file as the parameter and AddTail() it to this list.
  154.  
  155. 8. rd_SendPath [read-only]
  156.  
  157. This gives the name of the directory to look for files to send. Please
  158. note that this pointer may be NULL, ignore it in this case.
  159.  
  160. 9. rd_ReceivePath [read-only]
  161.  
  162. This gives the name of the directory to receive files into. Please
  163. note that this pointer may be NULL, ignore it in this case.
  164.  
  165. 10. rd_Options [read-only]
  166.  
  167. You can find a list of options or command line parameters here. `term'
  168. may place special data for you here. Please note that this pointer
  169. may be NULL, ignore it in this case.
  170.  
  171.  
  172. How to disconnect
  173. =================
  174. When the client is finished with whatever service it could provide,
  175. it must make sure that no read or write request is still pending.
  176. If the client made any changes to the serial parameters they should be
  177. restored to their original state. Finally, the client must call
  178. rs_Logoff() and release the semaphore as illustrated below:
  179.  
  180.    (*Semaphore -> rs_Logoff)(Data);
  181.  
  182.    ReleaseSemaphore((struct SignalSemaphore *)Semaphore);
  183.  
  184. After rs_Logoff() is called no further references may be made to the
  185. RendezvousData structure. You may still call the rs_Login()+rs_Logoff()
  186. pair as many times you like until you let go of the RendezvousSemaphore.
  187.  
  188.  
  189. Future extensions & author's address
  190. ====================================
  191. The rendezvous interface may grow in the future. If you need to make
  192. changes to the specifications or add extensions you should register
  193. them with me. If you need more information on how to implement a
  194. client or a host interface feel free to ask.
  195.  
  196. My postal address is:
  197.  
  198.    Olaf Barthel
  199.    Brabeckstrasse 35
  200.    D-30559 Hannover
  201.  
  202.    Federal Republic of Germany
  203.  
  204. eMail:
  205.  
  206.    olsen@sourcery.han.de
  207.  
  208. ***********************************************************************/
  209.